home *** CD-ROM | disk | FTP | other *** search
/ QRZ! Ham Radio 4 / QRZ Ham Radio Callsign Database - Volume 4.iso / files / packet / misc / stats.arc / DOC.DOC < prev    next >
Text File  |  1980-01-02  |  11KB  |  331 lines
  1. Documentation for WB6YMH/NK6K Stats package.
  2. Version 1.1, October 1987.
  3.  
  4.  
  5.  
  6. This set of programs is intended to be the start of a family of 
  7. programs to gather performance statistics and other information 
  8. about the amateur radio packet system.  A complete background on 
  9. the project was provided in a paper presented at the 6th ARRL 
  10. Computer Networking Conference.  A copy of the paper is included 
  11. in this release.
  12.  
  13. The following programs are currently included:
  14.  
  15. STATS - monitors output from a KISS TNC, displays activity on
  16. the screen and puts stats in LOG.
  17.  
  18. REPORT - reformats data from LOG file.
  19.  
  20. TOTALS - reformats data from LOG file.
  21.  
  22. PTOTALS - prints output from TOTALS program.
  23.  
  24. AVERAGE - averages data from REPORT program.
  25.  
  26.  
  27. The programs are written C and compiled with Microsoft C 
  28. 3.0 and 4.0.  They will be as easily transportable to other 
  29. versions of C as any other C program.
  30.  
  31. The STATS program uses two assembly language modules for an 
  32. interface to the PC's serial ports.  The SERIALIP.ASM module 
  33. provides interrupt driven serial I/O for IBM compatible COM1 and 
  34. COM2 serial ports.  The CDTMR.ASM module samples the Carrier 
  35. Detect line on the RS232 port at a 18.2 Hz rate. Obviously these 
  36. routines are very machine specific and would have to be heavily 
  37. modified or replaced when porting the STATS program to another 
  38. hardware environment.
  39.  
  40. Specifics on each program are discussed below.
  41.  
  42.  
  43. STATS
  44. ----
  45.  
  46. This program reads AX.25 frames in the KISS TNC format.  
  47. Information about the frame is summed in various counters.  These 
  48. counters are output into a log file once every reporting 
  49. interval.  The reporting interval is currently set at five 
  50. minutes.   The format of the records in the log file are in 
  51. MONFILE.H
  52.  
  53. At the end of each interval, STATS opens "log" in the current 
  54. directory, appends the new records, and then closes the file.  If 
  55. the log file can not be opened (disk full), STATS aborts.è
  56. STATS also writes all incoming frames on stdout.
  57.  
  58. The STATS program may be used either standalone or with an 
  59. W0RLI/WA7MBL compatible "mbbios" program.  The standalone version 
  60. supports a standard COM1 or COM2 serial port.  Non-standard ports 
  61. are supported by use of the "mbbios" program.  STATS will use the 
  62. mbbios program instead of the internal serial routine if mbbios 
  63. is loaded. 
  64.  
  65. Commands to STATS can be entered on the startup line, or after it 
  66. is running.  Once running, the command parser is entered by 
  67. hitting Alt-C.  The parser will then accept one command line, 
  68. then return to collecting data.  Multiple commands are separated 
  69. by ';'.  The commands are:
  70.  
  71.  
  72. BASE 
  73.  
  74.     Sets the base address of the COM port. This command is used 
  75.     when a "mbbios" program is used to support a non-standard COM 
  76.     port.  The specified BASE address is used by the background 
  77.     routine to sample the CD status line.  The BASE address is 
  78.     automatically set by the PORT command when the built in 
  79.     interrupt handler is used.  Example: BASE 768 sets the base 
  80.     address of a non-standard serial port to 768 (300 hex).
  81.  
  82.  
  83. BAUD
  84.  
  85.     Selects baud rate of the serial line to the KISS TNC, e.g. 
  86.     BAUD 4800.
  87.  
  88.  
  89. END
  90.  
  91.     Terminates execution.  Alt-X may also be used to exit 
  92.     instead of Alt-C END.
  93.  
  94.  
  95. HELP
  96.  
  97.     Displays the list of available commands.
  98.  
  99.  
  100. QUIT
  101.  
  102.     Synonym for END.
  103.  
  104.  
  105. PORT
  106.  
  107.     Selects the port for the KISS TNC connection, n = 0 or 1 if 
  108.     mbbios is not used.  Otherwise n maybe any port supported by 
  109.     mbbios. The default is 0 (com1).  è
  110. TIME
  111.  
  112.     Adds timestamp to each frame displayed by STATS.  Timestamp 
  113.     records are always included in the log file.
  114.  
  115.  
  116. The following hardware mod should be made if DCD on/off times are
  117. desired.
  118.  
  119. Since most of the current TNC designs use the DCD signal on the RS-232 
  120. interface as a connect status indicator it is necessary to modify 
  121. the TNC hardware slightly to provide a true modem DCD on the RS-232 
  122. interface.  The modification for the TNC 2 and clones is very 
  123. simple, consisting of a single jumper wire.  The jumper goes 
  124. between pin 2 of the modem disconnect header (DCD output from the 
  125. modem) and the pin of JMP1 which is NOT connected to +5 volts 
  126. (input to the DCD driver).  On the MFJ-1270B artwork the correct 
  127. pin of JMP1 is the one closest to the front panel.  The authors 
  128. have not researched modifications to other TNC designs, but it is 
  129. expected the modifications will be similar.  It is NOT necessary 
  130. to perform the DCD modification to run the monitoring software, 
  131. it is only necessary if the statistics of DCD activity are 
  132. desired.
  133.  
  134. Most terminal software used on packet will be unaffected by this
  135. modification, however most BBS software will require the jumper to 
  136. be removed for normal operation.
  137.  
  138.  
  139.  
  140.  
  141. REPORT
  142. ------
  143.  
  144. Report further summarizes and combines the information in the log 
  145. file built by STATS.  Data is emitted as one record per interval.  
  146. These records can then be passed through AVERAGE to produce data
  147. averaged over larger intervals.  The data can then passed to a 
  148. plotting program for display.  Lotus 123 was used to produce the 
  149. graphs in the conference proceedings.  The various items output 
  150. by REPORT have no great cosmic meaning, they serve as examples of 
  151. the kind of information we feel can tell us something about how 
  152. the network is running.  The intent is for others to add more 
  153. sophisticated reports as we get an idea of what it is we need to 
  154. know.
  155.  
  156.  
  157. The commands are summarized below.  An item enclosed in [] is 
  158. optional.
  159.  
  160. CIRCUIT
  161.  
  162.     Most of the data graphed in the conference proceedings was 
  163.     generated by this command.  It has no options.  The command è    generates one record per interval; the records contain the 
  164.     following fields:
  165.           time_stamp          Time stamp of the start of the 
  166.                               interval.
  167.           all circuits        Count of unique to/from pairs.
  168.           user circuits       Circuits excluding those sending 
  169.                               only occasional UI frames.  These
  170.                               are assumed to be beacons or NETROM
  171.                               node commands.
  172.           packets             All packets on channel
  173.           retried packets     Total data packets - unique data 
  174.                               packets
  175.           poll                All packets with poll bit set
  176.           final               All packets with final bit set
  177.           rnr                 RNR packets
  178.           rej                 REJ packets
  179.           bytes               total bytes (all bytes in all 
  180.                               packets)
  181.           udbytes             unique data bytes (data bytes in I 
  182.                               frames of unique packets)
  183.  
  184. END
  185.  
  186.     Exits REPORT.
  187.  
  188.  
  189. HELP
  190.  
  191.     Generates a list of valid commands.
  192.  
  193.  
  194. INPUT file
  195.  
  196.     Selects a file to use in place of the default "log".
  197.  
  198.  
  199. OUTPUT file
  200.  
  201.     Selects a file to use for the generated report instead of 
  202.     stdout.
  203.  
  204. HELP
  205.  
  206.     Displays the list of available commands.
  207.  
  208.  
  209. QUIT
  210.  
  211.     Exits REPORT.
  212.  
  213.  
  214. RAW  [T]
  215.           
  216.     This command displays all fields of all records selected by 
  217.     the RECORD command.  Hit the space key to abort the display.  è    The number printed under the TO call for circuit records is 
  218.     the record number.  RAW also totals all the data in F records 
  219.     and prints this total at the end of the display, providing a 
  220.     quick indication of the amount of data collect.  This command 
  221.     has one option, T.  If T is specified, only the F record 
  222.     total line is displayed.
  223.  
  224.  
  225. RECORD [c][d][f][i][t]
  226.  
  227.     This command selects record types for processing.  The record 
  228.     types are defined in the MONFILE.H file.  To select a record 
  229.     type, enter the type code(s) after the command name, e.g.
  230.           RECORD FT
  231.     selects timestamp and frequency records.  Record with no 
  232.     options will display the current setting.  The default is all 
  233.     types.
  234.  
  235.  
  236. RR
  237.  
  238.     RR has no options.  The command generates one record per 
  239.     interval; the records contain the following fields:
  240.           time_stamp          Time stamp of the start of the 
  241.                               interval.
  242.           packets             Total packets
  243.           i packets           total non-digipeated I frames
  244.           rr packets          total non-digipeater RR frames
  245.  
  246.  
  247. SELECT [call]
  248.  
  249.     This command selects a callsign.  Only circuit records 
  250.     containing this call as one of the endpoints are used in 
  251.     other processing.  The default is no call specified, i.e., 
  252.     all calls are used.  Only one call may be specified at a 
  253.     time, use select with no call to de-select.
  254.  
  255.  
  256.  
  257.  
  258. AVERAGE
  259. -------
  260.  
  261. This program takes the output from the one-interval-per-record 
  262. output of REPORT and averages them together.  Average takes two 
  263. commands on the startup line, -n and -t.  -n is followed by the 
  264. number of records that should be averaged.  For instance, the 
  265. basic reporting interval is five minutes.  If the data is to be 
  266. plotted in half hour points, use -n6.  This will average six 
  267. five-minute intervals together.
  268.  
  269. If -t is specified, the first data item in each record is assumed 
  270. to be a timestamp, which is then not averaged.
  271. è
  272.  
  273.  
  274. TOTALS
  275. ------
  276.  
  277. This program reads a log file through STDIN and generals a totals 
  278. file through STDOUT.  It produces four record types, detailed 
  279. below.  This program generates one record per station on the air, 
  280. one record per digipeater, and one record giving totals of all 
  281. packets and bytes heard on the frequency.  PTOTALS is used to 
  282. display the information output by TOTALS.
  283.  
  284. TOTALS takes one option on the command line, a call sign.  If 
  285. specified, only circuit records containing the specified call as 
  286. one of the end points are used.  Record types are:
  287.  
  288.      D - Totals for each digipeater.
  289.           call
  290.           total bytes
  291.           total packets
  292.  
  293.  
  294.      F - Totals for the frequency
  295.           total packets
  296.           total bytes
  297.           unique packets
  298.           unique bytes
  299.           l32 packets <= 32 bytes long
  300.           l64 packets <= 64 bytes long
  301.           l128 packets <= 128 bytes long
  302.           l256 packets <= 256 bytes long
  303.           g256 packets > 256 bytes long
  304.           dcd on ticks
  305.           dcd off ticks
  306.  
  307.  
  308.      S - totals for a station
  309.           station call
  310.       total rx bytes
  311.           total rx unique data bytes
  312.           total rx non-digipeated data bytes
  313.           total rx data bytes
  314.       total tx bytes
  315.           total tx unique data bytes
  316.           total tx non-digipeated data bytes
  317.           total tx data bytes
  318.  
  319. If a callsign was specified, a Z record is emitted as the first 
  320. record in the output file.  This record is the same as an S 
  321. record, and contains the data for the selected call.
  322.  
  323.  
  324.  
  325. PTOTALSè-------
  326.  
  327. This program formats the output from the TOTALS program.
  328. There are no options.
  329.  
  330.  
  331.